API

Example

This example shows a very simple lifecycle of a Store: from creation, to adding and getting some data, and then registering and removing a listener.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
console.log(store.getRow('pets', 'fido'));
// -> {species: 'dog'}

store.setCell('pets', 'fido', 'color', 'brown');
console.log(store.getCell('pets', 'fido', 'color'));
// -> 'brown'

const listenerId = store.addTableListener('pets', () => {
  console.log('changed');
});

store.setCell('pets', 'fido', 'sold', false);
// -> 'changed'

store.delListener(listenerId);

See also

• The Basics guides
• Using Schemas guides
• Hello World demos
• Todo App demos

Since

v1.0.0

Examples

This example creates a MergeableStore.

import {createMergeableStore} from 'tinybase';

const store = createMergeableStore('store1');

console.log(store.getContent());
// -> [{}, {}]
console.log(store.getMergeableContent());
// -> [[{}, '', 0], [{}, '', 0]]

This example creates a MergeableStore with some initial data:

import {createMergeableStore} from 'tinybase';

const store = createMergeableStore('store1').setTables({
  pets: {fido: {species: 'dog'}},
});

console.log(store.getContent());
// -> [{pets: {fido: {species: 'dog'}}}, {}]
console.log(store.getMergeableContent());
// ->
[
  [
    {
      pets: [
        {
          fido: [
            {species: ['dog', 'Nn1JUF-----FnHIC', 290599168]},
            '',
            2682656941,
          ],
        },
        '',
        2102515304,
      ],
    },
    '',
    3506229770,
  ],
  [{}, '', 0],
];

This example creates a MergeableStore with some initial data and a TablesSchema:

import {createMergeableStore} from 'tinybase';

const store = createMergeableStore('store1')
  .setTables({pets: {fido: {species: 'dog'}}})
  .setTablesSchema({
    pets: {
      species: {type: 'string'},
      sold: {type: 'boolean', default: false},
    },
  });

console.log(store.getContent());
// -> [{pets: {fido: {sold: false, species: 'dog'}}}, {}]
console.log(store.getMergeableContent());
// ->
[
  [
    {
      pets: [
        {
          fido: [
            {
              sold: [false, 'Nn1JUF----2FnHIC', 2603026204],
              species: ['dog', 'Nn1JUF----1FnHIC', 2817056260],
            },
            '',
            2859424112,
          ],
        },
        '',
        1640515891,
      ],
    },
    '',
    2077041985,
  ],
  [{}, '', 0],
];

Since

v5.0.0

Examples

This example creates a Store.

import {createStore} from 'tinybase';

const store = createStore();
console.log(store.getTables());
// -> {}

This example creates a Store with some initial data:

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}}}

This example creates a Store with some initial data and a TablesSchema:

import {createStore} from 'tinybase';

const store = createStore()
  .setTables({pets: {fido: {species: 'dog'}}})
  .setTablesSchema({
    pets: {
      species: {type: 'string'},
      sold: {type: 'boolean', default: false},
    },
  });
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog', sold: false}}}

See also

The Basics guides

Since

v1.0.0

Examples

This example retrieves the data in a single Row.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    fido: {species: 'dog'},
    felix: {species: 'cat'},
  },
});
console.log(store.getRow('pets', 'fido'));
// -> {species: 'dog'}

This example retrieves a Row that does not exist, returning an empty object.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
console.log(store.getRow('pets', 'felix'));
// -> {}

Since

v1.0.0

Examples

This example retrieves a single Cell.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
console.log(store.getCell('pets', 'fido', 'species'));
// -> 'dog'

This example retrieves a Cell that does not exist, returning undefined.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
console.log(store.getCell('pets', 'fido', 'color'));
// -> undefined

Since

v1.0.0

Examples

This example retrieves a single Value.

import {createStore} from 'tinybase';

const store = createStore().setValues({open: true, employees: 3});
console.log(store.getValue('employees'));
// -> 3

This example retrieves a Value that does not exist, returning undefined.

import {createStore} from 'tinybase';

const store = createStore().setValues({open: true, employees: 3});
console.log(store.getValue('website'));
// -> undefined

Since

v3.0.0

Examples

This example sets the data of a single Row.

import {createStore} from 'tinybase';

const store = createStore().setRow('pets', 'fido', {species: 'dog'});
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}}}

This example attempts to set the data of an existing Store with partly invalid, and then completely invalid, Row objects.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

store.setRow('pets', 'fido', {color: 'brown', bug: []});
console.log(store.getTables());
// -> {pets: {fido: {color: 'brown'}}}

store.setRow('pets', 'fido', 42);
console.log(store.getTables());
// -> {pets: {fido: {color: 'brown'}}}

Since

v1.0.0

Examples

This example adds a single Row.

import {createStore} from 'tinybase';

const store = createStore();
console.log(store.addRow('pets', {species: 'dog'}));
// -> '0'
console.log(store.getTables());
// -> {pets: {'0': {species: 'dog'}}}

This example attempts to add Rows to an existing Store with partly invalid, and then completely invalid, Row objects.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {'0': {species: 'dog'}}});

console.log(store.addRow('pets', {species: 'cat', bug: []}));
// -> '1'
console.log(store.getTables());
// -> {pets: {'0': {species: 'dog'}, '1': {species: 'cat'}}}

console.log(store.addRow('pets', 42));
// -> undefined
console.log(store.getTables());
// -> {pets: {'0': {species: 'dog'}, '1': {species: 'cat'}}}

Since

v1.0.0

Examples

This example sets the value of a single Cell.

import {createStore} from 'tinybase';

const store = createStore().setCell('pets', 'fido', 'species', 'dog');
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}}}

This example sets the data of a single Cell by mapping the existing value.

import {createStore} from 'tinybase';

const increment = (cell) => cell + 1;
const store = createStore().setTables({pets: {fido: {visits: 1}}});

store.setCell('pets', 'fido', 'visits', increment);
console.log(store.getCell('pets', 'fido', 'visits'));
// -> 2

This example attempts to set the data of an existing Store with an invalid Cell value.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

store.setCell('pets', 'fido', 'bug', []);
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}}}

Since

v1.0.0

Examples

This example sets a single Value.

import {createStore} from 'tinybase';

const store = createStore().setValue('open', true);
console.log(store.getValues());
// -> {open: true}

This example sets the data of a single Value by mapping the existing Value.

import {createStore} from 'tinybase';

const increment = (value) => value + 1;
const store = createStore().setValues({employees: 3});

store.setValue('employees', increment);
console.log(store.getValue('employees'));
// -> 4

This example attempts to set an invalid Value.

import {createStore} from 'tinybase';

const store = createStore().setValues({employees: 3});

store.setValue('bug', []);
console.log(store.getValues());
// -> {employees: 3}

Since

v3.0.0

Examples

This example makes changes to two Cells, first outside, and secondly within, a transaction. In the second case, the Row listener is only called once.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
store.addRowListener('pets', 'fido', () => console.log('Fido changed'));

store
  .setCell('pets', 'fido', 'color', 'brown')
  .setCell('pets', 'fido', 'sold', false);
// -> 'Fido changed'
// -> 'Fido changed'

store.transaction(() =>
  store
    .setCell('pets', 'fido', 'color', 'walnut')
    .setCell('pets', 'fido', 'sold', true),
);
// -> 'Fido changed'

This example makes multiple changes to one Cell. The Cell listener is called once - and with the final value - only if there is a net overall change.

import {createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
store.addCellListener(
  'pets',
  'fido',
  'color',
  (store, tableId, rowId, cellId, newCell) => console.log(newCell),
);

store.transaction(() =>
  store
    .setCell('pets', 'fido', 'color', 'black')
    .setCell('pets', 'fido', 'color', 'brown')
    .setCell('pets', 'fido', 'color', 'walnut'),
);
// -> 'walnut'

store.transaction(() =>
  store
    .setCell('pets', 'fido', 'color', 'black')
    .setCell('pets', 'fido', 'color', 'walnut'),
);
// -> undefined
// No net change during the transaction, so the listener is not called.

This example makes multiple changes to the Store, including some attempts to update a Cell and Value with invalid values. The doRollback callback receives information about the changes and invalid attempts, and then judges that the transaction should be rolled back to its original state.

import {createStore} from 'tinybase';

const store = createStore()
  .setTables({pets: {fido: {species: 'dog', color: 'brown'}}})
  .setValues({open: true});

store.transaction(
  () =>
    store
      .setCell('pets', 'fido', 'color', 'black')
      .setCell('pets', 'fido', 'eyes', ['left', 'right'])
      .setCell('pets', 'fido', 'info', {sold: null})
      .setValue('open', false)
      .setValue('employees', ['alice', 'bob']),
  () => {
    const [, , changedCells, invalidCells, changedValues, invalidValues] =
      store.getTransactionLog();
    console.log(store.getTables());
    console.log(changedCells);
    console.log(invalidCells);
    console.log(changedValues);
    console.log(invalidValues);
    return invalidCells['pets'] != null;
  },
);
// -> {pets: {fido: {species: 'dog', color: 'black'}}}
// -> {pets: {fido: {color: ['brown', 'black']}}}
// -> {pets: {fido: {eyes: [['left', 'right']], info: [{sold: null}]}}}
// -> {open: [true, false]}
// -> {employees: [['alice', 'bob']]}

console.log(store.getTables());
// -> {pets: {fido: {species: 'dog', color: 'brown'}}}
console.log(store.getValues());
// -> {open: true}

Since

v1.0.0

Examples

This example registers a listener that responds to any changes to a specific Row.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addRowListener(
  'pets',
  'fido',
  (store, tableId, rowId, getCellChange) => {
    console.log('fido row in pets table changed');
    console.log(getCellChange('pets', 'fido', 'color'));
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'fido row in pets table changed'
// -> [true, 'brown', 'walnut']

store.delListener(listenerId);

This example registers a listener that responds to any changes to any Row.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addRowListener(
  null,
  null,
  (store, tableId, rowId) => {
    console.log(`${rowId} row in ${tableId} table changed`);
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'fido row in pets table changed'
store.setTable('species', {dog: {price: 5}});
// -> 'dog row in species table changed'

store.delListener(listenerId);

This example registers a listener that responds to any changes to a specific Row, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addRowListener(
  'pets',
  'fido',
  (store, tableId, rowId) =>
    store.setCell('meta', 'update', `${tableId}_${rowId}`, true),
  true,
);

store.delCell('pets', 'fido', 'color');
console.log(store.getTable('meta'));
// -> {update: {pets_fido: true}}

store.delListener(listenerId);

Since

v1.0.0

Examples

This example registers a listener that responds to any changes to a specific Cell.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  'pets',
  'fido',
  'color',
  (store, tableId, rowId, cellId, newCell, oldCell, getCellChange) => {
    console.log('color cell in fido row in pets table changed');
    console.log([oldCell, newCell]);
    console.log(getCellChange('pets', 'fido', 'color'));
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in pets table changed'
// -> ['brown', 'walnut']
// -> [true, 'brown', 'walnut']

store.delListener(listenerId);

This example registers a listener that responds to any changes to any Cell.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  null,
  null,
  null,
  (store, tableId, rowId, cellId) => {
    console.log(
      `${cellId} cell in ${rowId} row in ${tableId} table changed`,
    );
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in pets table changed'
store.setTable('species', {dog: {price: 5}});
// -> 'price cell in dog row in species table changed'

store.delListener(listenerId);

This example registers a listener that responds to any changes to a specific Cell, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  'pets',
  'fido',
  'color',
  (store, tableId, rowId, cellId) =>
    store.setCell('meta', 'update', `${tableId}_${rowId}_${cellId}`, true),
  true,
);

store.delCell('pets', 'fido', 'color');
console.log(store.getTable('meta'));
// -> {update: {pets_fido_color: true}}

store.delListener(listenerId);

Since

v1.0.0

Examples

This example registers a listener that responds to any changes to a specific Value.

import {createStore} from 'tinybase';

const store = createStore().setValues({open: true, employees: 3});
const listenerId = store.addValueListener(
  'employees',
  (store, valueId, newValue, oldValue, getValueChange) => {
    console.log('employee value changed');
    console.log([oldValue, newValue]);
    console.log(getValueChange('employees'));
  },
);

store.setValue('employees', 4);
// -> 'employee value changed'
// -> [3, 4]
// -> [true, 3, 4]

store.delListener(listenerId);

This example registers a listener that responds to any changes to any Value.

import {createStore} from 'tinybase';

const store = createStore().setValues({open: true, employees: 3});
const listenerId = store.addValueListener(null, (store, valueId) => {
  console.log(`${valueId} value changed`);
});

store.setValue('employees', 4);
// -> 'employees value changed'
store.setValue('open', false);
// -> 'open value changed'

store.delListener(listenerId);

This example registers a listener that responds to any changes to a specific Value, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setValues({open: true, employees: 3});
const listenerId = store.addValueListener(
  'employees',
  (store) => store.setValue('updated', true),
  true,
);

store.delValue('employees');
console.log(store.getValues());
// -> {open: true, updated: true}

store.delListener(listenerId);

Since

v3.0.0

Examples

This example creates a Store, persists it to the browser's session storage as a JSON string, changes the persisted data, updates the Store from it, and finally destroys the Persister again.

import {createStore} from 'tinybase';
import {createSessionPersister} from 'tinybase/persisters/persister-browser';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSessionPersister(store, 'pets');

await persister.save();
console.log(sessionStorage.getItem('pets'));
// -> '[{"pets":{"fido":{"species":"dog"}}},{}]'

sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
await persister.load();
console.log(store.getTables());
// -> {pets: {toto: {species: 'dog'}}}

await persister.destroy();
sessionStorage.clear();

This example creates a Store, and automatically saves and loads it to the browser's session storage as a JSON string. Changes to the Store data, or the persisted data (implicitly firing a StorageEvent), are reflected accordingly.

import {createStore} from 'tinybase';
import {createSessionPersister} from 'tinybase/persisters/persister-browser';

const store = createStore();
const persister = createSessionPersister(store, 'pets');

await persister.startAutoLoad([{pets: {fido: {species: 'dog'}}}, {}]);
await persister.startAutoSave();

store.setTables({pets: {felix: {species: 'cat'}}});
// ...
console.log(sessionStorage.getItem('pets'));
// -> '[{"pets":{"felix":{"species":"cat"}}},{}]'

// In another browser tab:
sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
// -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})

// ...
console.log(store.getTables());
// -> {pets: {toto: {species: 'dog'}}}

await persister.destroy();
sessionStorage.clear();

Since

v1.0.0

Examples

This example creates a DurableObjectSqlStoragePersister object and persists the Store to Durable Object SQLite storage as a JSON serialization into the default tinybase table. It uses this within the createPersister method of a WsServerDurableObject instance.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object with a custom table name and SQL command logging for debugging.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      'my_app_store',
      (sql, params) => console.log('SQL:', sql, params),
      (error) => console.error('Persistence error:', error),
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object using fragmented mode to avoid Cloudflare's 2MB row limit for large stores.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      {mode: 'fragmented'},
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object using fragmented mode with a custom storage prefix.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      {mode: 'fragmented', storagePrefix: 'my_app_'},
    );
    return persister;
  }
}

Since

v6.3.0

Example

This example creates a LocalPersister object and persists the Store to the browser's local storage.

import {createStore} from 'tinybase';
import {createLocalPersister} from 'tinybase/persisters/persister-browser';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createLocalPersister(store, 'pets');

await persister.save();
console.log(localStorage.getItem('pets'));
// -> '[{"pets":{"fido":{"species":"dog"}}},{}]'

await persister.destroy();
localStorage.clear();

Since

v1.0.0

Examples

This example creates a PglitePersister object and persists the Store to a local PGlite database as a JSON serialization into the my_tinybase table. It makes a change to the database directly and then reloads it back into the Store.

import {PGlite} from '@electric-sql/pglite';
import {createStore} from 'tinybase';
import {createPglitePersister} from 'tinybase/persisters/persister-pglite';

const pglite = await PGlite.create();
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = await createPglitePersister(
  store,
  pglite,
  'my_tinybase',
);
await persister.save();
// Store will be saved to the database.

console.log((await pglite.query('SELECT * FROM my_tinybase;')).rows);
// -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]

await pglite.query(`UPDATE my_tinybase SET store = $1 WHERE _id = '_';`, [
  '[{"pets":{"felix":{"species":"cat"}}},{}]',
]);

await persister.load();
console.log(store.getTables());
// -> {pets: {felix: {species: 'cat'}}}

await persister.destroy();
await pglite.close();

This example creates a PglitePersister object and persists the Store to a local PGlite database with tabular mapping.

import {PGlite} from '@electric-sql/pglite';
import {createStore} from 'tinybase';
import {createPglitePersister} from 'tinybase/persisters/persister-pglite';

const pglite = await PGlite.create();
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = await createPglitePersister(store, pglite, {
  mode: 'tabular',
  tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
});

await persister.save();
console.log((await pglite.query('SELECT * FROM pets;')).rows);
// -> [{_id: 'fido', species: '"dog"'}]
// Note that Cells and Values are JSON-encoded in PostgreSQL databases.

await pglite.query(
  `INSERT INTO pets (_id, species) VALUES ('felix', '"cat"')`,
);
await persister.load();
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

await persister.destroy();
await pglite.query('DROP TABLE IF EXISTS pets');
await pglite.close();

Since

5.2.0

Example

This example creates a SessionPersister object and persists the Store to the browser's session storage.

import {createStore} from 'tinybase';
import {createSessionPersister} from 'tinybase/persisters/persister-browser';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSessionPersister(store, 'pets');

await persister.save();
console.log(sessionStorage.getItem('pets'));
// -> '[{"pets":{"fido":{"species":"dog"}}},{}]'

await persister.destroy();
sessionStorage.clear();

Since

v1.0.0

Examples

This example creates a SqliteWasmPersister object and persists the Store to a local SQLite database as a JSON serialization into the my_tinybase table. It makes a change to the database directly and then reloads it back into the Store.

import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
import {createStore} from 'tinybase';
import {createSqliteWasmPersister} from 'tinybase/persisters/persister-sqlite-wasm';

const sqlite3 = await sqlite3InitModule();
const db = new sqlite3.oo1.DB(':memory:', 'c');
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSqliteWasmPersister(
  store,
  sqlite3,
  db,
  'my_tinybase',
);

await persister.save();
// Store will be saved to the database.

console.log(db.exec('SELECT * FROM my_tinybase;', {rowMode: 'object'}));
// -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]

db.exec(
  'UPDATE my_tinybase SET store = ' +
    `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
);
await persister.load();
console.log(store.getTables());
// -> {pets: {felix: {species: 'cat'}}}

await persister.destroy();

This example creates a SqliteWasmPersister object and persists the Store to a local SQLite database with tabular mapping.

import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
import {createStore} from 'tinybase';
import {createSqliteWasmPersister} from 'tinybase/persisters/persister-sqlite-wasm';

const sqlite3 = await sqlite3InitModule();
const db = new sqlite3.oo1.DB(':memory:', 'c');
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSqliteWasmPersister(store, sqlite3, db, {
  mode: 'tabular',
  tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
});

await persister.save();
console.log(db.exec('SELECT * FROM pets;', {rowMode: 'object'}));
// -> [{_id: 'fido', species: 'dog'}]

db.exec(`INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`);
await persister.load();
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

await persister.destroy();

Since

v4.0.0

Example

This example creates two empty MergeableStore objects, creates a LocalSynchronizer for each, and starts synchronizing them. A change in one becomes evident in the other.

import {createMergeableStore} from 'tinybase';
import {createLocalSynchronizer} from 'tinybase/synchronizers/synchronizer-local';

const store1 = createMergeableStore();
const store2 = createMergeableStore();

const synchronizer1 = createLocalSynchronizer(store1);
const synchronizer2 = createLocalSynchronizer(store2);

await synchronizer1.startSync();
await synchronizer2.startSync();

store1.setTables({pets: {fido: {species: 'dog'}}});
// ...
console.log(store2.getTables());
// -> {pets: {fido: {species: 'dog'}}}

store2.setRow('pets', 'felix', {species: 'cat'});
// ...
console.log(store1.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

await synchronizer1.destroy();
await synchronizer2.destroy();

Since

v5.0.0

Since

v5.4.0

Example

This example creates two WsSynchronizer objects to synchronize one MergeableStore to another via a server.

import {createMergeableStore} from 'tinybase';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
import {WebSocket, WebSocketServer} from 'ws';

const server = createWsServer(new WebSocketServer({port: 8047}));

const store1 = createMergeableStore();
const store2 = createMergeableStore();

const synchronizer1 = await createWsSynchronizer(
  store1,
  new WebSocket('ws://localhost:8047'),
);
const synchronizer2 = await createWsSynchronizer(
  store2,
  new WebSocket('ws://localhost:8047'),
);

await synchronizer1.startSync();
await synchronizer2.startSync();

store1.setTables({pets: {fido: {species: 'dog'}}});
store2.setTables({pets: {felix: {species: 'cat'}}});

// ...
console.log(store1.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
console.log(store2.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

await synchronizer1.destroy();
await synchronizer2.destroy();
await server.destroy();

Since

v5.0.0

Examples

This example creates an empty Store at the top level of a React application. Even though the App component is rendered twice, the Store creation only occurs once by default.

import React from 'react';
import {createRoot} from 'react-dom/client';
import {createStore} from 'tinybase';
import {useCreateStore} from 'tinybase/ui-react';

const App = () => {
  const store = useCreateStore(() => {
    console.log('Store created');
    return createStore().setTables({pets: {fido: {species: 'dog'}}});
  });
  return <span>{store.getCell('pets', 'fido', 'species')}</span>;
};

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App />);
// -> 'Store created'

root.render(<App />);
// No second Store creation

console.log(app.innerHTML);
// -> '<span>dog</span>'

This example creates an empty Store at the top level of a React application. The App component is rendered twice, each with a different top-level prop. The useCreateStore hook takes the fidoSpecies prop as a dependency, and so the Store is created again on the second render.

import React from 'react';
import {createRoot} from 'react-dom/client';
import {createStore} from 'tinybase';
import {useCreateStore} from 'tinybase/ui-react';

const App = ({fidoSpecies}) => {
  const store = useCreateStore(() => {
    console.log(`Store created for fido as ${fidoSpecies}`);
    return createStore().setTables({pets: {fido: {species: fidoSpecies}}});
  }, [fidoSpecies]);
  return <span>{store.getCell('pets', 'fido', 'species')}</span>;
};

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App fidoSpecies="dog" />);
// -> 'Store created for fido as dog'

console.log(app.innerHTML);
// -> '<span>dog</span>'

root.render(<App fidoSpecies="cat" />);
// -> 'Store created for fido as cat'

console.log(app.innerHTML);
// -> '<span>cat</span>'